Skip to content

docs: add maintainer onboarding, revival playbook, and adoption criteria#6

Merged
psjamesp merged 3 commits into
pr/05-workflowsfrom
pr/06-docs
Apr 21, 2026
Merged

docs: add maintainer onboarding, revival playbook, and adoption criteria#6
psjamesp merged 3 commits into
pr/05-workflowsfrom
pr/06-docs

Conversation

@HeyItsGilbert
Copy link
Copy Markdown
Member

Stack position: 6 of 7

The three operational documents. These are the self-serve reference for anyone joining the org, reviving a tool, or evaluating a tool for adoption.

What's in this PR

docs/maintainer-onboarding.md — Day-1 checklist:

  • GitHub org access and 2FA requirement
  • Branch protection verification (8 settings to check)
  • PSGallery API key issuance process with exact naming convention: PowerShellOrg-<RepoName>-<YYYY-MM>, glob = module name, 365-day expiry
  • Local build stack setup and smoke test
  • Communication norms: triage SLAs, review expectations, release announcement process, escalation paths

docs/revival-playbook.md — Five phases, all checklist format:

  • Phase 0: Transfer and inventory (access, PSGallery, baseline metrics)
  • Phase 1: Issue triage with closure comment templates (needs-info, wontfix, stale pre-adoption)
  • Phase 2: PR triage with decision tree and "taking over a PR" template
  • Phase 3: Build modernization — seven substeps (3a Pester → 3b psake → 3c PowerShellBuild → 3d PSScriptAnalyzer → 3e GHA CI → 3f GHA release → 3g coverage baseline)
  • Phase 4: First release gate checklist
  • Phase 5: Ongoing cadence table and graduation path

docs/adoption-criteria.md — Six must-be-true criteria, six org commitments, four submitter commitments, adoption workflow with timelines

Council questions

  1. Revival playbook phases: does this match your mental model from the PSDepend revival? What did we do that isn't captured here?
  2. API key naming convention (PowerShellOrg-<Repo>-<YYYY-MM>): should the date be the creation month or the expiry month? Currently it's the creation month.
  3. 9-month inactivity threshold (repeated from governance PR — mentioned in onboarding too): does this need to be longer given volunteer bandwidth?
  4. "At least 30 days between releases if there are merged changes" in the ongoing cadence table: is this realistic? Should it be "no more than 90 days"?
  5. Adoption criteria — 6-month maintainer commitment: too long, too short, or right?

Base: pr/05-workflows — merge PRs 1–5 first.

HeyItsGilbert and others added 3 commits April 21, 2026 14:54
profile/README.md: tool roster (Plaster, PSDepend) with status badges,
adopt-your-tool CTA linking to the adoption request template,
help-wanted CTA linking to good-first-issues and help-wanted across
the org, links to governance and CoC.
maintainer-onboarding.md: day-1 access checklist, branch protection
verification, PSGallery key issuance process (naming convention
PowerShellOrg-<Repo>-<YYYY-MM>), CI bootstrap, communication norms.

revival-playbook.md: five-phase checklist — Phase 0 (inventory/transfer),
Phase 1 (issue triage with comment templates), Phase 2 (PR triage with
decision tree), Phase 3 (build modernization a–g), Phase 4 (first
release gate), Phase 5 (ongoing cadence and graduation path).

adoption-criteria.md: six must-be-true criteria, six org commitments,
four submitter commitments, workflow with 7d ack / 30d decision.
@psjamesp psjamesp merged commit 82a7bd9 into pr/05-workflows Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants